Inside Macintosh: Telephony /

Chapter 6 - Telephone Tools / Telephone Tools Reference

Tool-Defined Functions /

MyVDEF

Called to handle general telephony operations.

pascal short MyVDEF (
                     TELHandle hTEL, 
                     TELTermPtr pTELTerm, 
                     TELDNHandle hDN, 
                     TELCAHandle hCA, 
                     short msg, 
                     long p1, 
                     long p2, 
                     long p3);

hTEL

A handle to a telephone record for the user's terminal.

pTELTerm

A pointer to a telephone terminal record. This record is the same record that is pointed to by the pTELTerm field of the telephone record specified by the hTEL parameter.

hDN

A handle to a directory number structure.

hCA

A handle to a call appearance structure.

msg

A constant that identifies the type of message being sent to the telephone tool. See "Main Code Resource Messages," beginning on page 6-11 for a complete description of the available messages for a main code resource.

p1

The first parameter for the specified message.

p2

The second parameter for the specified message.

p3

The third parameter for the specified message.

function result

A result code. See the description below for specific codes you can return.

DESCRIPTION

The MyVDEF function is the entry point to the main code resource of a telephone tool. It should inspect the message specified by the msg parameter and respond accordingly. The first four parameters (hTEL, pTELTerm, hDN, and hCA) specify Telephone Manager data structures that your tool can access to get information it needs to perform the operation requested by the msg parameter. For instance, if the msg parameter contains telAnswerCallMsg, your tool can inspect the call appearance structure specified by the hCA parameter to get information about the incoming call. Some of these parameters are unused for some messages.

The meaning of the parameters p1, p2, and p3 is dependent on the message type specified by the msg parameter. See the descriptions of the main code resource messages beginning on page 6-11 for information about these parameters for each message.

Your MyVDEF function should return, as its function result, a result code indicating the outcome of the request. You can return an operating-system result code (for example, a Memory Manager error, if you are unable to allocate the memory you need) or a Telephone Manager result code. If your tool does not support the specified operation or feature, it should return the code telFeatNotSupp. If your tool does support the specified feature but the feature is not currently subscribed, your tool should return the code telFeatNotSub. If your tool supports the specified feature and the feature is currently subscribed but not currently available, your tool should return the code telFeatNotAvail. If your tool supports the requested feature but the feature is already active, your tool should return the code telFeatActive.

SPECIAL CONSIDERATIONS

When relaying requests from applications to your tool, the Telephone Manager checks any handles passed in the requests, making sure they are on a list (maintained internally by the Telephone Manager) of valid handles. However, the Telephone Manager can sometimes relay an invalid handle--one for a terminal, directory number, or call appearance that your tool no longer supports. If your tool receives an invalid handle, it should return one of the following three result codes: telBadTermErr (for terminals), telBadDNErr (for directory numbers), or telBadCAErr (for call appearances). In addition, your tool should set to -1 the field tRef of the telephone record, the dnRef field of the directory number record, or the caRef field of the call appearance record, depending on the type of the invalid handle.